<!doctype html>


<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>deferred.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
     var _typeTreeName = "goog";
     var _fileTreeName = "Source";
  </script>

  <script src="static/js/doc.js">
  </script>


  <meta charset="utf8">
</head>

<body onload="grokdoc.onLoad();">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>





<div class="colmask rightmenu">
<div class="colleft">
    <div class="col1">
      <!-- Column 1 start -->

<div id="title">
       <span class="fn">deferred.js</span>
</div>

<div class="g-section g-tpl-75-25">
  <div class="g-unit g-first" id="description">
    Classes for tracking asynchronous operations and handling the
 results. The Deferred object here is patterned after the Deferred object in
 the Twisted python networking framework.

 See: <a href="http://twistedmatrix.com/projects/core/documentation/howto/defer.html">http://twistedmatrix.com/projects/core/documentation/howto/defer.html</a>

 Based on the Dojo code which in turn is based on the MochiKit code.
  </div>
  

        <div class="g-unit" id="useful-links">
          <div class="title">Useful links</div>
          <ol>
            <li><a href="closure_third_party_closure_goog_mochikit_async_deferred.js.source.html"><span class='source-code-link'>Source Code</span></a></li>
            <li><a href="http://code.google.com/p/closure-library/source/browse/closure/third_party/closure/goog/mochikit/async/deferred.js">Git</a></li>
          </ol>
        </div>
</div>

<h2 class="g-first">File Location</h2>
  <div class="g-section g-tpl-20-80">
    <div class="g-unit g-first">
      <div class="g-c-cell code-label">_party/closure/goog/mochikit/async/deferred.js</div>
    </div>
  </div>
<hr/>


  <h2>Classes</h2>
 <div class="fn-constructor">
        <a href="class_goog_async_Deferred.html">
          goog.async.Deferred</a><br/>
        <div class="class-details">A Deferred represents the result of an asynchronous operation. A Deferred
instance has no result when it is created, and is &amp;quot;fired&amp;quot; (given an initial
result) by calling <code>callback</code> or <code>errback</code>.

Once fired, the result is passed through a sequence of callback functions
registered with <code>addCallback</code> or <code>addErrback</code>. The functions may
mutate the result before it is passed to the next function in the sequence.

Callbacks and errbacks may be added at any time, including after the Deferred
has been &amp;amp;amp;amp;amp;quot;fired&amp;amp;amp;amp;amp;quot;. If there are no pending actions in the execution sequence
of a fired Deferred, any new callback functions will be called with the last
computed result. Adding a callback function is the only way to access the
result of the Deferred.

If a Deferred operation is cancelled, an optional user-provided cancellation
function is invoked which may perform any special cleanup, followed by firing
the Deferred&amp;amp;amp;amp;amp;#39;s errback sequence with a <code>CancelledError</code>. If the
Deferred has already fired, cancellation is ignored.</div>
 </div>
 <div class="fn-constructor">
        <a href="class_goog_async_Deferred_AlreadyCalledError.html">
          goog.async.Deferred.AlreadyCalledError</a><br/>
        <div class="class-details">An error sub class that is used when a Deferred has already been called.</div>
 </div>
 <div class="fn-constructor">
        <a href="class_goog_async_Deferred_CancelledError.html">
          goog.async.Deferred.CancelledError</a><br/>
        <div class="class-details">An error sub class that is used when a Deferred is cancelled.
TODO(brenneman): Cancelled -&gt; American English Canceled.</div>
 </div>
      
<br/>

  <div class="legend">
        <span class="key publickey"></span><span>Public</span>
        <span class="key protectedkey"></span><span>Protected</span>
        <span class="key privatekey"></span><span>Private</span>
  </div>









<div class="section">
  <table class="horiz-rule">


  </table>
</div>




  <h2>Global Functions</h2>





<div class="section">
  <table class="horiz-rule">


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.async.Deferred.call"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.async.Deferred.</span><span class="entryName">call<span class="args">()</span>
        </span>
      </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

   
  </td>


  <td class="view-code">
     <a href="closure_third_party_closure_goog_mochikit_async_deferred.js.source.html#line59">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.async.Deferred.cancelled"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.async.Deferred.</span><span class="entryName">cancelled<span class="args">()</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>
      </div>


     <div class="entryOverview">
       Creates a Deferred that has already been cancelled.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>&nbsp;
            The new Deferred.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_third_party_closure_goog_mochikit_async_deferred.js.source.html#line602">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.async.Deferred.fail"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.async.Deferred.</span><span class="entryName">fail<span class="args">(<span class="arg">res</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>
      </div>


     <div class="entryOverview">
       Creates a Deferred that has an initial error result.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">res</span>
        : <div class="fullType"><span class="type">*</span></div>
        <div class="entryOverview">The error result.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>&nbsp;
            The new Deferred.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_third_party_closure_goog_mochikit_async_deferred.js.source.html#line590">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.async.Deferred.succeed"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.async.Deferred.</span><span class="entryName">succeed<span class="args">(<span class="arg">opt_result</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>
      </div>


     <div class="entryOverview">
       Creates a Deferred that has an initial result.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">opt_result</span>
        : <div class="fullType"><span class="type">*</span></div>
        <div class="entryOverview">The result.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>&nbsp;
            The new Deferred.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_third_party_closure_goog_mochikit_async_deferred.js.source.html#line577">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.async.Deferred.when"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.async.Deferred.</span><span class="entryName">when<span class="args">(<span class="arg">value</span>,&nbsp;<span class="arg">callback</span>,&nbsp;<span class="arg">opt_scope</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>
      </div>


     <div class="entryOverview">
       Normalizes values that may or may not be Deferreds.

If the input value is a Deferred, the Deferred is branched (so the original
execution sequence is not modified) and the input callback added to the new
branch. The branch is returned to the caller.

If the input value is not a Deferred, the callback will be executed
immediately and an already firing Deferred will be returned to the caller.

In the following (contrived) example, if <code>isImmediate</code> is true
then 3 is alerted immediately, otherwise 6 is alerted after a 2-second delay.

<pre class="lang-js prettyprint">
var value;
if (isImmediate) {
value = 3;
} else {
value = new goog.async.Deferred();
setTimeout(function() { value.callback(6); }, 2000);
}

var d = goog.async.Deferred.when(value, alert);
</pre>
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">value</span>
        : <div class="fullType"><span class="type">*</span></div>
        <div class="entryOverview">Deferred or normal value to pass to the callback.</div>
     </td>
   </tr>
     
   <tr class="odd">
     <td>
        <span class="entryName">callback</span>
        : <div class="fullType"><span>?</span><span class="type">function (this:T, ?): </span></div>
        <div class="entryOverview">The callback to execute.</div>
     </td>
   </tr>
     
   <tr class="even">
     <td>
        <span class="entryName">opt_scope</span>
        : <div class="fullType">(<span class="type">T</span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">An optional scope to call the callback in.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="class_goog_async_Deferred.html">goog.async.Deferred</a></span></div>&nbsp;
            A new Deferred that will call the input callback with the input value.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_third_party_closure_goog_mochikit_async_deferred.js.source.html#line641">code &raquo;</a>
  </td>
     </tr>


  </table>
</div>






      <!-- Column 1 end -->
    </div>

        <div class="col2">
          <!-- Column 2 start -->
          <div class="col2-c">
            <h2 id="ref-head">Directory async</h2>
            <div id="localView"></div>
          </div>

          <div class="col2-c">
            <h2 id="ref-head">File Reference</h2>
            <div id="sideFileIndex" rootPath="" current="_party/closure/goog/mochikit/async/deferred.js"></div>
          </div>
          <!-- Column 2 end -->
        </div>
</div>
</div>

</body>
</html>
